home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / language / embedded / ibm / r3sim.arc / SIM_R3.DOC < prev    next >
Text File  |  1989-07-08  |  16KB  |  344 lines
  1. SIM_R3.DOC
  2.     I. Introduction
  3.        A. Who wrote sim_r3 and why
  4.        B. Disclaimer
  5.     II. Using sim_r3.exe
  6.        A. Items on the display
  7.        B. Explanation of commands
  8.     III. Recompiling sim_r3
  9.        A. For the IBM-PC
  10.           1. Using Microsoft C 5.0 or higher
  11.           2. Using another compiler
  12.        B. For non-IBM compatible machines
  13.  
  14. I. Introduction
  15. I. A. Who wrote sim_r3 and why
  16.  
  17.      All files in this archive were written entirely by myself, 
  18.      Joseph Schachner.  I can be contacted via Compuserve 
  19.      (73637,3437).
  20.  
  21.      sim_r3 was written to support a project where I work which  
  22.      is planning to use a 68705R3.  Because the 68705 program and 
  23.      data memory is compeletly internal, debugging a running 68705 
  24.      is nearly impossible.  Of course, the 68705 can be emulated 
  25.      by hardware, at a cost of several thousand dollars.  This is 
  26.      an excellent debugging solution.  However, simulation with 
  27.      software provides a very good debugging environment for 
  28.      almost no cost.  sim_r3 is in use by another engineer at my 
  29.      workplace, and has already found several bugs.
  30.  
  31.  
  32. I. B. Disclaimer
  33.  
  34.      Although I am an experienced 6800 family programmer, and I 
  35.      took great care to insure the accuracy of this emulation, and 
  36.      several bugs have been found and fixed as the program has 
  37.      been used, I make no representation that this program in its 
  38.      current form is either bug free or will precisely meet your 
  39.      needs.  The source code is distributed in this archive for 
  40.      you to add (or change) any feature.  If you change and 
  41.      recompile sim_r3.exe, PLEASE do not distribute it without 
  42.      noting your changes in this file!
  43.  
  44.      Changes:
  45.      V1.21 - added clear of latched external interrupt to 
  46.           simulated reset routine in instr.c.  This change is 
  47.           present in the source code in this archive.  This was an 
  48.           omission in 1.2 and earlier, but the only symptom is, if 
  49.           you issue 'I' and then reset before simulating servicing 
  50.           the interrupt the interrupt persists. 8-July-1989 Joe 
  51.           Schachner
  52.  
  53. II. Using sim_r3.exe
  54.  
  55.      Normally, one develops for a 6805 family processor using an 
  56.      assembler and possibly a linker.  The output from the 
  57.      development tools is a file containing Motorola hex format 
  58.      records (S0, S1 and S9).
  59.  
  60.      The simulator loads in the Motorola hex file in response to 
  61.      the 'L' command (see below).  By default trace display and 
  62.      log file capture are on.  The simulator responds to your 
  63.      commands input in either upper or lower case.
  64.  
  65.      Note: the simulator's trace log file is named "sim_r3.log" 
  66.      and is created in the current directory when the simulator 
  67.      is started.  If a file with the same name existed, it is 
  68.      replaced by the new (empty) file.
  69.  
  70.      sim_r3 is a very small program.  When compiled with Microsoft 
  71.      C 5.0, it is about 55,000 bytes.  Therefore, even 256K of 
  72.      memory is more than enough.  If you plan to turn on the log 
  73.      file (to capture the trace on disk), it helps to have a hard 
  74.      disk to keep execution speed up.
  75.  
  76.  
  77. II. A. Items on the display
  78.  
  79.      When sim_r3 is started, it puts up the following on the top 
  80.      seven lines of the display:
  81.  
  82. 68705R3 Simulator V1.2  6-July-1989              Disp+log ON    Halted
  83. R - disp/chg regs       L file - load Sx & reset        E - toggle TIE  G - Go
  84. T - trace on/off        B addr - Break at address (go)  I - /INT      S - Step
  85. X - Reset       M addr - Mem view/mod   Z - Disassem    H - Halt      Q - Quit
  86.  
  87.  
  88. ______________________________________________________________________________
  89.  
  90.      The top line (line 1) shows program status.  The next three 
  91.      lines list commands, which will be explained below. The fifth 
  92.      line is always blank.  The sixth line is where all commands 
  93.      appear as you type them, and where prompts and messages 
  94.      appear; this line will be referred to as the "prompt line".
  95.  
  96.      The next line (line 7) is a solid bar separating the fixed 
  97.      top portion of the screen from the trace display, which 
  98.      scrolls up from line 24 to line 8 and vanishes.  Disassembly 
  99.      also appears on lines 8 to 24.
  100.  
  101.      The status line shows the program revision, whether trace 
  102.      results will be displayed (and optionally captured to a 
  103.      file), and whether simulation is in progress.  The next 
  104.      section, "Explanation of commands", provides more information 
  105.      on these fields.
  106.  
  107. II. B. Explanation of commands
  108.  
  109.     R - display / change registers
  110.      Text similar to the following appears on the prompt line:
  111.  
  112.      PC= 100, A= 00, X= 00, SP= 07F, CCR=08 (I)  Change?(reg) _
  113.  
  114.      The user may enter (at least the first character of) the name 
  115.      of any register shown, sim_r3 will prompt for a new value.  
  116.      Press return without entering a register name to end this 
  117.      command without changing a register.  Note: the values of the 
  118.      registers are displayed and entered in hex.  Bits that are on 
  119.      in the condition code register are also shown using the 
  120.      characters HINZC.
  121.  
  122.     L file - Load Sx and reset
  123.      sim_r3 reads motorola hex records.  Only S1 and S9 records 
  124.      are significant.  Checksums are ignored.  Loading is 
  125.      extremely fast.  When the "S9" record is encountered the load 
  126.      terminates.  End of file without an "S9" record causes an 
  127.      error message to be displayed.
  128.  
  129.      If the load completes without error, a message similar to the 
  130.      following is displayed:
  131.  
  132.      File test.sx loaded
  133.  
  134.      When a hex file has been loaded, a simulated reset is 
  135.      automatically performed (see 'X' command), below.
  136.  
  137.     E - Toggle TIE in
  138.      sim_r3 simulates all four timer modes.  The 'E' command 
  139.      changes the state of the timer's external input.  The current 
  140.      state is displayed on the prompt line.  The effect of 
  141.      changing the state of the timer's external input depends on 
  142.      the mode set by bits 4 and 5 (TIE and TIN) in the Timer 
  143.      Control Register.  See section 5.3 of the MC68(7)05 R/U 
  144.      Series technical data book, Motorola ADI-977.
  145.  
  146.     G - Go
  147.      The 'Halted' label changes to 'Running' and simulation 
  148.      commences at the current PC.  The breakpoint address is 
  149.      unchanged.  Simulation will halt when the PC equals the 
  150.      breakpoint address on an opcode fetch, or if the 'H' command 
  151.      is entered (see below).
  152.  
  153.     T - Trace display (and logfile) on/off
  154.      If display is on when this command is entered, it is turned 
  155.      off.  Logfile capture is always off when display is off.  If 
  156.      display is off when this command is entered, the prompt 
  157.      "Enable logfile also?(Y/N) " will appear.  After the prompt 
  158.      is answered, the label on line one will say either "Display 
  159.      ON" or "Disp+Log ON".  The format of the log file is 
  160.      identical to that of the trace display.
  161.  
  162.      Note: simulation proceeds MUCH faster if the trace display is 
  163.      turned off.
  164.  
  165.      An example trace display (part of a log file) appears below.  
  166.      It was generated by the commands 'L test.sx', 'B 10b'.
  167.  
  168. 100  A6 55         LDA   #$55           101=>55 ACCUM<=55                     2
  169. 102  48            LSLA                 ACCUM=>55 ACCUM<=AA                   6
  170. 103  47            ASRA                 ACCUM=>AA ACCUM<=D5                  10
  171. 104  97            TAX                  X_REG<=D5                            12
  172. 105  BF 50         STX   $50            050<=D5                              17
  173. 107  3C 50         INC   $50            050=>D5 050<=D6                      23
  174. 109  26 FC         BNE   $107                                                27
  175. 107  3C 50         INC   $50            050=>D6 050<=D7                      33
  176. 109  26 FC         BNE   $107                                                37
  177. ^    ^             ^                     ^                                   ^
  178. |    |             |                     addr=>data (read)                   |
  179. |    |             |                     addr<=data (write)        Cycle count
  180. |    |             |                     All values in hex.         in decimal
  181. |    |             Assembly              Register names ACCUM,
  182. |    |             Mnemonics             X_REG, SP may appear.
  183. |    |
  184. |    Opcode and operand bytes for this instruction, in hex.
  185. |
  186. PC for opcode, in hex
  187.  
  188.      The example trace continues until finally location $50 
  189.      becomes zero and the BNE is not taken:
  190.  
  191. 109  26 FC         BNE   $107                                               437
  192. 107  3C 50         INC   $50            050=>FF 050<=00                     443
  193. 109  26 FC         BNE   $107                                               447
  194.  
  195.      At this point the prompt line shows "Breakpoint reached" and 
  196.      the simulation is halted.
  197.  
  198.     B addr - Go and break at addr
  199.      The breakpoint address is set from the address (in hex) 
  200.      following the 'B'. After that, operation is the same as 'G', 
  201.      above.  See 'T', above,  for an example of this command's 
  202.      usage.
  203.  
  204.     I - /INT
  205.      Latches an external interupt.  If the interrupt mask is not 
  206.      set sim_r3 will simulate interrupt response prior to 
  207.      beginning the next simulated instruction.
  208.  
  209.     S - Step
  210.      Simulate one instruction at the current PC.  Similar to 'G' 
  211.      except simulation is automatically halted after one 
  212.      instruction.  The breakpoint address is unchanged.
  213.  
  214.     X - Reset
  215.      sim_r3 simulates a reset, loading the PC from the reset 
  216.      vector, initializing the data direction registers and the 
  217.      timer, and the timer control register from the Mask Options 
  218.      Register, and setting the interrupt mask and resetting the 
  219.      stack pointer to 7F, and (version 1.21 and higher) also 
  220.      clears internal latched interrupt if any.
  221.  
  222.     M addr - memory view/change
  223.      The address (in hex) is read as if read by a program running 
  224.      in the 68705, and the address and value are displayed on the 
  225.      prompt line.  If 'Enter' is pressed, the next location is 
  226.      displayed.  If a hex value is entered, the value is written 
  227.      to the displayed location and then the next location is 
  228.      displayed.  To get out of this routine, enter a non-hex-digit 
  229.      ascii character, for example 'q'.
  230.      Example: M 100
  231.      100 A6      
  232.      101 55      
  233.      102 48  q
  234.  
  235.     Z - disassemble
  236.      Z displays assembly mnemonics for the next 15 instructions in 
  237.      memory starting at the current program counter, or, if an 
  238.      address is entered, for the next 15 instructions starting at 
  239.      that address.  The display looks similar to a trace display 
  240.      except no read/write data is shown and machine cycles are not 
  241.      shown.  Disassembly has no effect on simulation state.
  242.  
  243.     H - halt
  244.      If simulation is in progress, it is stopped.  The 'Running' 
  245.      label on the first line changes to 'Halted'.
  246.  
  247.     Q - quit
  248.      Leave sim_r3.  The following appears on the prompt line:
  249.      Logfile closed - normal exit
  250.  
  251.    Enter - 
  252.      Just pressing 'Enter' does nothing but cause the line under 
  253.      the prompt line to be redrawn.  This is useful in case you 
  254.      accidentally press "Escape" and DOS blows away the line.
  255.  
  256. III. Recompiling sim_r3
  257.  
  258. III. A. For the IBM-PC
  259. III. A. 1. Using Microsoft C 5.0 or higher
  260.  
  261.      This supplied code may be compiled without changes.  The 
  262.      supplied make file, makefile.mak, is for Polytron's POLYMAKE 
  263.      to invoke the Microsoft C compiler.  The makefile is written 
  264.      in a manner which makes it very easy to convert for 
  265.      Microsoft's make, which is supplied with Microsoft C.  Only a 
  266.      few lines need to be moved.  Exact direction are in a comment 
  267.      in makefile.mak.
  268.  
  269. III. A. 2.Using another compiler
  270.  
  271.      Most of this program is "plain vanilla" C, and will port 
  272.      unchanged.  However, the functions which clear the screen and
  273.      position the text cursor are not portable.  clearscreen and 
  274.      settextposition call routines from Microsoft C 5.0's 
  275.      graphics library.  Most C compilers will supply library 
  276.      routines for these functions, which may be substituted.
  277.      Delete_line uses the Microsoft C function "int86" to invoke 
  278.      one of the DOS BIOS services.  Again, most C compiles for the 
  279.      PC will have some way to invoke the BIOS services, which may 
  280.      be substituted.
  281.  
  282.      If your compiler does NOT have cursor position and screen 
  283.      functions, you may use ANSI.SYS to supply these functions.  
  284.      ANSI.SYS is a file supplied with IBM DOS.  It may be built 
  285.      into the DOS of some clones.  ANSI.SYS must be memory 
  286.      resident.  This requires the statement "DEVICE=ANSI.SYS" in 
  287.      your config.sys file when you boot.  Then, simply writing a 
  288.      special sequence of characters to stdout will cause ANSI.SYS 
  289.      to perform these functions.  See the IBM DOS technical 
  290.      reference for documentation on control codes for ANSI.SYS.  
  291.      The code for using ANSI.SYS will look a lot like the code for 
  292.      driving a VT-52 (a Digital Equipment Corp terminal), which is 
  293.      included.  However, the control codes are not the same: 
  294.      ANSI.SYS uses DEC VT-100 control codes.
  295.  
  296.      sim.h includes a #define for the type of graphics routines, 
  297.      at the moment either MSC or VT52.  I suggest you add another 
  298.      #define and add your new C code right after each occurance of 
  299.      "#ifdef VT52 ... #endif" in the routines settextposition and 
  300.      clearscreen, both in sim_r3.c; and in the routine delete_line 
  301.      in instr.c.
  302.  
  303. III. B. For non-IBM compatible machines
  304.  
  305.      As long as your machine has an 80x25 character text display, 
  306.      the only changes which need to be made are to support the 
  307.      functions settextposition, clearscreen, and delete_line.
  308.  
  309.      sim.h includes a #define for the type of graphics routines, 
  310.      at the moment either MSC or VT52.  I suggest you add another 
  311.      #define and add your new C code right after each occurance of 
  312.      "#ifdef VT52 ... #endif" in the routines settextposition and 
  313.      clearscreen, both in sim_r3.c; and in the routine delete_line 
  314.      in instr.c.
  315.  
  316.      Note that if your computer emulates a DEC VT 52 terminal, or 
  317.      if you will use this on a computer that actually drives a 
  318.      terminal that can handle VT 52 control codes, then all you 
  319.      have to do is uncomment "#define VT52" instead of "#define 
  320.      MSC" in sim.h and recompile.
  321.  
  322.      It is interesting to note that exactly the same parts of the 
  323.      program need to be changed for a non-IBM compatible as for a 
  324.      true IBM compatible but not Microsoft C 5.0 or higher.  This 
  325.      is because of the lack of standardization of even the most 
  326.      rudimentary graphics functions; each compiler is different.  
  327.      Perhaps X Windows will finally change this sad situation.
  328.  
  329.      One further reflection on graphics standardization: I 
  330.      mentioned above that sim_r3 was about 55,000 bytes when 
  331.      compiled by Microsoft C 5.0.  When compiled by Mark Williams 
  332.      C for the Atari ST it is only about 36,000 bytes.  This 
  333.      difference is due mostly to the fact that support for the 
  334.      needed graphics functions and VT52 emulation is part of the 
  335.      ST's operating system, but requires routines from Microsoft C 
  336.      5.0's graphics library in the IBM version.  Consider the 
  337.      amount of memory wasted in a multitasking environment if each 
  338.      application includes the graphics library and ten or twenty 
  339.      applications are running...  This has nothing to do with 
  340.      sim_r3, but it's one of my favorite subjects!  My apologies.  
  341.      I hope sim_r3 is useful to you.
  342.  
  343.      --- Joe Schachner 8-July-1989
  344.